Cream of the Crop 22/Cream of the Crop 22.iso/comm/yrndl140.zip/yd.doc

Text File | 1996-09-24 | 95KB | 2,261 lines

YD.DOC        24 Sep 1996        (from YRNDL140.ZIP)
(c) 1996 by Jerry Levy        Marblehead, MA USA
[e-mail]

YARNDIAL v. 1.40 is the full release version.
Version number of installer (YDINSTL.CMD) also set to 1.40.

No significant changes were made to YD.DOC in going from v.
1.34 to 1.40.  (Some sections were significantly upgraded in
going from 1.3 to 1.34).

This is the documentation file accompanying YARNDIAL in
YRNDL140.ZIP.  Any comments, problems, bugs, irregularities
or inconsistencies in operation, and suggestions should be
sent to me at [e-mail].  I will try to respond to every
one.

This documentation file should be printed at 10 cpi (Courier or
other monospaced font preferred; a Times font, which is not
monospaced, affords readable copy).

IN-JOY ALERT
If you use the IN-JOY dialer, read over Section 16.00 very
carefully.  Give serious thought to setting a routing interface
name in  each host setup that is unique and different from all
other interface names used by IN-JOY or your other dialers (if you
use others).  This interface name is set in an options page for
PPP and no doubt will be equally configurable in a corresponding
SLIP options page when SLIP is supported by IN-JOY.  YARNDIAL
will use this interface name you assign to positively correlate an
existing connection to the YARNDIAL installation when YARNDIAL
starts up.  It can only do this competently if you use unique
interface names, different for all connections and providers.

A fix is now implemented that addresses the IN-JOY problem where a
phantom router interface is sometimes left standing when phone
connection and connection to the router (i.e., to your Internet
Service Provider) have been terminated.  INTERFACE_REMOVALE in
the YD_PARMS.DAT file may be edited to enable the fix.  Options
are discussed in Section 16.00 and again summarized in the
YD_PARMS.DAT file created upon installation of YARNDIAL.  Default
is INTERFACE_REMOVAL=0 (does not enable a corrective action).

If INTERFACE_REMOVAL is set equal to 1 or 2 (refer section 16.00),
and a routing wass left up when YARNDIAL exits, it is removed and a
message is returned indicating deletion of the routing, with indication
of the destination and router addresses.

The changes accompanying the evolution of beta version 1.3x of
YARNDIAL.CMD are
        An installer (YDINSTL.CMD) is now part of the Yarndial
          package.  New versions of YARNDIAL (1.3 on) should
          always be installed with the installer shipped with it.

        YDINSTL's file-search logic debugged.

        Error-trapping defaulted to 'disabled' and cleaned
          up.  Near the beginning of both YARNDIAL.CMD and
          YDINST.CMD is a variable, local_error_trapping, which
          will toggle error-trapping on (if = 1) or off (=0).

        Improvements made in how we recognize whether we are
          logged on to a provider and whether it is the correct
          connection for our YARNDIAL/YARN installation.
          Especially improved is such support when IN-JOY is the
          dialer.

        Improved manual-configuration.  Not recommended because
           manual configuration is tedious, but it does work.
           It is a lot easier to configure SLIPPM, and let the
           installer draw stored parameters from the TCPOS2.INI
           file where they are stored.

        A partial fix (as yet untested) for multi-modem systems.

        Option added to keep the phone connection up when YARNDIAL
          has completed its operations, instead of always killing
          the connection.

        The Step-by-Step Yarn installation instructions: typos
          regarding metamail installation corrected; a more
          accurate and useful example of a mailcap file provided;
          an example of how to use a simple .CMD file to gain
          control over what directory metamail.exe uses as the
          default for saving decoded attachments.

ABOUT VERSIONS 1.3x and later:  Beta versions 1.3 and later of
YARNDIAL represent significant improvements over earlier versions.
In addition to bug fixes and general cleanup of the code, an
installer has been added which supports use of IBM/Advantis'
IAK Dialer (for Advantis network only), the IBM SLIPPM dialer
(the Dial-Other-Internet-Providers utility), PPP.EXE and
SLIP.EXE dialup strings, and ability to manually configure by
means of prompted entry of parameters.  Support for the IN-JOY
Dialer,the ILINK/2 dialer, and ability to use others of your own
choosing was added and augmented as v. 1.3x evolved.

I plan to issue a final GA version 1.4 by October 1, 1996.

This program is and will stay freeware.

DIALERS
For use of third-party dialers such as IN-JOY or ILINK/2, or if
you use PPP.EXE or SLIP.EXE dialup strings, it is most convenient
and strongly recommended that you go through the motions of
setting up SLIPPM even where you do not intend to use SLIPPM to
make the connection.  Think of SLIPPM in that context as a PM
program to conveniently store paramters where the YARNDIAL
installer can most readily get at them.

SLIPPM is a fine utility, and in most instances where you are
connecting to a provider with other than the IBM/Advantis IAK
dialer, alone or with add-on script packages such as PPDIAL29, it
is serviceable.  ILINK/2 is an improvement over SLIPPM in
many respects and piggybacks on SLIPPM-created dialup
configurations.  IN-JOY is another improved dialer, but unlike
ILINK/2, it is totally independent of the SLIPPM, SLIP.EXE
and/or PPP.EXE programs and of the TCPOS2.INI file used by SLIPPM
and ILINK/2.  IN-JOY presently (version 09) does not support
SLIP but SLIP support is soon to be added to IN-JOY features.

I am committed to adding and improving support of third-party
dialers provided I can obtain a copy to work with and the
interface is not obscure.  So far, only ILINK/2 and IN-JOY have
been brought to my attention as alternatives to SLIPPM, PPP.EXE
and SLIP.EXE.

Contact me if I do not support your pet dialer ([e-mail]).

                        CONTENTS
 1.00  Installation For The Impatient User (Assumes Yarn And
        Souper Are Installed And They Work
 2.00  What Is Yarndial?
 3.00  Key Features
 4.00  Copyright Notice And Disclaimers
 5.00  Passwords - Disclaimer
 6.00  How Does The Installer Work?
 7.00  Example: Setting Up For Two Users (My Installation)
 8.00  What Does YDINSTL.CMD Do?
 9.00  .CMD Files Created - Meaning Of Customization
10.00  Recreating Objects (Running OBJECTS.CMD - A Peculiarity)
11.00  Warp, Souper, Yarn: Versions Tested
12.00  You Have Not Installed Yarn And Souper Yet?
13.00  History
14.00  Should You Upgrade Anything Before You Install?
        14.10   Souper
        14.20   IBM/Advantis IAK Dialer
        14.30   SLIPPM.EXE (Dial-Other-Internet-Providers Utility
                 and SLIP Upgrades
15.00  Before You Run YDINSTL.CMD
16.00  Notes On Using the IN-JOY Dialer
17.00  About The Fix-Interrupted-Import Option On The Main
        YARNDIAL Menu
18.00  Souper Command-Line Options
19.00  Issues That May Come Up During Or After Install
20.00  Manual Install
21.00  Manual Install: The Password Problem
22.00  Connection_Type: The Different Choices
23.00  More About Dialup_String: A Programming Note
24.00  Zip And UnZip Files
25.00  Compression Executables: OS/2 Versus MS-DOS
26.00  Some Other Breed Of Compression Utilities
27.00  Files For Setting Up Yarn And Souper From Scratch
28.00  Install EMXRT, METAMAIL, MIME64 (recommended)
        28.10 EMXRT09B (optional)
        28.20 MIME64 (optional)
        28.30 METAMAIL (optional)
           28.31  Metamail Tricks
           28.32  Doing Attachments Under Yarn, Metamail
                   Operation, Decoding Multipart Messages, and
                   Handling Non-Conforming MIME Attachments
              28.321  Doing Attachments Under Yarn, etc.
              28.322  Decoding Non-Conforming Mime Attachments
              28.323  Decoding MIME With MIME64.EXE
              28.324  Content-type Editing:  MIME Associations
29.00  Step-By-Step Installation Of Yarn and Souper
30.00  Note About Adding Newsgroups
31.00  Setting Up And Installing For Multiple Users
32.00  Connection Killed Or Not When YARNDIAL Ends
33.00  Where To Get Software And Helpful Documentation
34.00  Bugs and Error-Trapping






1.00  INSTALLATION FOR THE IMPATIENT USER (ASSUMES YARN AND
       SOUPER ARE INSTALLED AND THEY WORK)
    1.10   First unzip YRNDL134.ZIP archive into a temporary
folder.  You have probably done that if you are reading this.

Files in the YRNDL134.ZIP archive are
        FILE.DIZ        Zipfile Description
        README.1ST      A lot shorter than YD.DOC
        YD.DOC          This file
        YDINSTL.CMD     The installer
        YARNDIAL.CMD
        GO.EXE          From GO_15.ZIP, needed by YARNDIAL
        GO_15.ZIP       Please open at your leisure, read
                         the documentation and send Carsten
                         his postcard.
        Also an \ICONS\ subdirectory containing all of the icons
          needed

If you unzipped YRNDL134.ZIP with PkZip without using the -d
option, you will not have a subdirectory named ICONS.  That
will not interfere with installation.  YDINSTL will manage
to find the icons.

       1.20   If you are using the IBM/Advantis IAK Dialer
proceed directly to the next step (1.30).

If you are using either SLIPPM (the IBM Dial-Other-Internet-
Providers utility) or the ILINK/2 dialer, you MUST set up
SLIPPM and verify it can connect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.

If you are using either the IN-JOY dialer, or a SLIP.EXE or
PPP.EXE dialup string to connect, you SHOULD set up
SLIPPM and verify it can conect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.  This is
because the YARNDIAL installer (YDINSTL.CMD) can extract
parameters from the TCPOS2.INI file used to store SLIPPM
setup information.

In setting up SLIPPM, you MUST fill in the names of your news
server, your mail gateway (i.e., your SMTP server), your POP
mail server, your pop login ID, and your pop password.  This is
not required for SLIPPM operation but the YARNDIAL installer
(YDINSTL.CMD) needs them and will automatically incorporate those
parameters into YARNDIAL's data file.

       1.30   Double-click on YDINSTL.CMD and follow the
instructions in screen prompts.


2.00    WHAT IS YARNDIAL?
YARNDIAL.CMD is a menu-driven front end for C.T. Huang's
OS/2 Souper and Yarn off-line News and Mail reader programs.
YARNDIAL is a ReXX utility running under OS/2 Warp.  It is
designed to automate the steps needed to retrieve and send news
articles and mail and while doing so to provide a more versatile,
friendlier interface for users than could be accomplished using
ordinary batch files.

YARNDIAL and its installer (YDINSTL.CMD) should work with any
version of OS/2 Warp (3.0).  Beta testers have confirmed that fixes
applied to YARNDIAL v. 1.32(beta) and beyond permit it to work with
the OS/2 Merlin beta.

ReXX must be installed for YARNDIAL and its installer to run.

Yarn and Souper must be correctly installed and functioning (the
true test of "correctly installed").  YARNDIAL only functions as a
front end and control panel for Souper and its interfaces with
Yarn, and is not a substitute.

YARNDIAL's opening menu allows you seven choices:

   MAIN SELECTION MENU
   1  Only import Mail
   2  Only import News Articles
   3  Only import, but both Mail AND News
   4  Only export (send Mail, Posts, Replies, and Follow-ups)
   5  Everything: Get mail and news AND send Posts, Replies,
      and Follow-ups
   6  Complete an interrupted importation of mail/news
      or rebuild a corrupted YARN history file
   7  Souper options:  one-time-only changes in how souper
      runs:
         Catchup on News
         Maximum News Packet Size
         Do not retrieve newsgroup articles longer than set
           number of lines
         Read-only for Mail: Don't empty POP3 mailbox
   Press:
       1 2 3 4 5 6 7   Executes functions as shown; goes
                         off-line when done
   or  ! @ # $ % ^ &   Same functions; connection remains up
   To exit now and close connection: Escape key
   To exit YarnDial, but leave any existing connection up: CTRL-Q
   Enter Selection:

Note: The ! @ # $ % ^ & choices represent shift-1, shift-2,
through shift-7 on a US-English keyboard.  Those alternates may be
changed to suit your own keyboard.


3.00  KEY FEATURES
o  Automatic dialup, connection, retrieval and sending of
news and/or mail, and (usually) signoff.  Optionally, can be run
so connection remains up when YARNDIAL finishes.

o Ability under certain circumstances to use an existing
SLIP or PPP connection to a provider.

o  Ability to select read-only for mail retrieval (doesn't empty
your POP3 mailbox).  I did not extend this to read-only for news
retrieval (i.e., to prevent your NEWSRC file from updating).  You
can edit the Souper parameters in YD_PARMS.DAT file following
installation to achieve this end (add -r to the
getnews_xtra_options element).

o  Ability to use a variety of dialup and connect options.
Supported are: the IBM/Advantis IAK Dialer,  IBM's Dial-
Other-Internet-Providers utility (SLIPPM.EXE),  PPP.EXE and
SLIP.EXE dialup strings, the IN-JOY dialer (only in-joy
v. 09 tested so far) and ILINK/2.  Other dialers can be used.

o  Menu-driven, for convenient selection of tasks.

o  Ability to choose/change a limited number of Souper
command-line options (menu, during install).

o  Ability to choose/change some Souper command-line options
(menu, when running YARNDIAL).

o  A YARNDIAL menu item which allows you to complete an
importation of news or mail which had been interrupted,  and
to call up the Yarn utility REBUILD to restore damaged Yarn
spool and history files.  (You don't need to understand this:
if you were downloading news and mail and it never showed
up, or your machine quit in the middle, or the lights went
out, maybe this will provide a fix.)

o  YDINSTL.CMD provides a near-automated (prompted)
installation process if you already have installed Yarn and
Souper and they work.

o  Some ability exists to discriminate if the connection
that is up is the correct connection for the particular user
for which YARNDIAL was installed.  For the IN-JOY dialer
this works best if one selects a unique interface name
when configuring IN-JOY to connect to your provider.  Refer
Section 16.00 for more on use of the IN-JOY dialer.

o  Ability when you run YARNDIAL to do catchup on news.
Catchup marks as read all but some number you specify of
unread articles in each news group.  Catchup as implemented
in YARNDIAL uses the same "catchup" number for all
newsgroups.

o  Among the Souper command-line options you can choose when
you run YDINSTL.CMD or at runtime when YARNDIAL is executed
are:
      Set maximum size of the news packet you can download
      in a single session
  and
      Limit retrieval of news articles to those with no more than
      some maximum number you set of lines in the body of the
      article.


4.00  COPYRIGHT NOTICE AND DISCLAIMERS
        YDINSTL.CMD is Copyright 1996 by Jerry Levy
           (all rights reserved)
        YARNDIAL.CMD is Copyright 1995 and 1996 by Jerry Levy
                   (all rights reserved)
        YD.DOC is Copyright 1995 and 1996 by Jerry Levy
                   (all rights reserved)
These are provided as-is and without charge, with no
warranty expressed or implied as to merchantability or
fitness for any particular purpose.  All responsibility for
any and all incidental and consequential damages is
disclaimed.  These programs and associated text files are
freeware.  They may be distributed without restriction
providing: (1) this notice and disclaimer remain intact, (2)
all programs and files are included and unchanged, and (3)
they are distributed either in the original .zip archive or
the archive after being unzipped into a folder or onto a
disk or other medium.  Use of either or both of these
programs constitutes acceptance of these terms by all users.

GO.EXE and GO_15.ZIP are  (c) 1993-95 by Carsten Wimmer and
are included with permission.
YARN.ICO is (c) by Chin Huang and is included with
permission.


5.00   PASSWORDS - DISCLAIMER
Some passwords are extracted from dialer setup files, and
while installing for use of the IBM/Advantis IAK Dialer,
we prompt for the Advantis password.  To keep these
passwords free from the casual eye, we scramble them before
they are written to YD_PARMS.DAT.  YARNDIAL unscrambles them
to use them.  Bear in mind that this is very low-tech
password protection.  It is minimal protection against a
threat posed by a skilled programmer or dedicated interloper.


6.00   HOW DOES THE INSTALLER WORK?
YDINSTL.CMD fetches information from one or more of: the IAK
dialer's DIALER.INI file, the TCPOS2.INI file, the IN-JOY
HOSTS.DAT file, and/or the YARN CONFIG file.

It goes after and processes other information
it finds on its own prompts you to enter.  YDINSTL then creates a
data file  (YD_PARMS.DAT) which is written to the home directory
for the Yarn user setup for which you are doing a YARNDIAL
installation.  YD_PARMS.DAT stores ALL of the installation-
specific parameters YARNDIAL needs in order to run.

YDINSTL also creates a folder on the desktop which houses program
objects for five objects; four for customized ReXX utility
programs created by YDINSTL for this user and a fifth object in
the folder for running YARNDIAL.

Another customized program (OBJECTS.CMD) is created that will
restore the Desktop Folder and its five Program Objects should you
need to.  This program is stored in the user's Home directory
also.

The folder name includes the name of the home directory of the
Yarn user setup you installed for.

The utility programs themselves (as opposed to their program
objects) are stored in the user's home directory.

YDINSTL IS RUN SEPARATELY FOR EACH YARN USER SETUP
If you set up more than one user when you set up YARN you need to
run YDINSTL separately for each one of them.


7.00   EXAMPLE: SETTING UP FOR TWO USERS (MY INSTALLATION)
In my setup I have two users, each with its own YARN directory,
For each, the HOME directories are the same as the YARN
directories.  This is somewhat unconventional but it works like a
charm and solves some problems I need not go into here (drop me a
note if interested).

I have set up one user for connection to the IBM/Advantis system
(using the IBM/Advantis IAK Dialer to establish a SLIP
connection), and I have set up a second user for connection via
PPP to the ATT WorldNet service (using IBM's Dial-Other-Internet-
Provider utility, SLIPPM.EXE, to connect, or the IN-JOY or ILINK/2
dialers to connect).

        NOTE:  When you set up SLIPPM, you will be asked to assign
        a name for that entry (first box on first page of the
        entry form).  Contrary to what I had once recommended, YOU
        SHOULD USE ALL UPPERCASE FOR THE NAME.

        WHY?   Because when slippm is run, some information, such
        as the running total of number of connections, is saved in
        TCPOS2.INI, under the same name, but the name in all-
        uppercase.  If the application name you specified was
        lowercase or mixed cases, you will store your application
        parameters under that name and you will create a separate
        entry (all uppercase) for the connect data.  If your
        application name is all-uppercase, your connect data are
        consolidated under a single uppercase .INI file
        "application" name.


Following is how I created my Yarn and Home Directories. Please
read Sections 27.00, 28.00 and 29.00 (Setting up Yarn and Souper)
for all the other things one needs to do in addition to setting
up directories.

   Unzip YRN2_09x.ZIP into a temporary folder.

   From an OS/2 command line after changing to that temporary
   directory run
         ENGLISH E:\ADVANTIS and then ENGLISH E:\WORLDNET.
   This creates separate E:\ADVANTIS and E:\WORLDNET directories
   for YARN.

   Add the following to your CONFIG.SYS file and reboot (We do
   this first for the ADVANTIS installation, then for WORLDNET):
        SET YARN=E:\ADVANTIS
        SET HOME=E:\ADVANTIS
        SET TZ=EST5EDT

   Open an OS/2 Window session, change to the E:\ADVANTIS
   directory, and run
        ADDUSER.EXE
   defining E:\ADVANTIS as the home directory, and filling in the
   other blanks.

   Repeat that process for the WORLDNET installation: re-edit
   CONFIG.SYS by replacing the ADVANTIS lines with
       SET YARN=E:\WORLDNET and SET HOME=E:\WORLDNET
   reboot; change to the E:\WORLDNET directory in an OS/2 window
   session; run ADDUSER.EXE from the command line, define
   E:\WORLDNET as the home directory, and fill in the other
   blanks.

(Also set up a NEWSRC file for each home directory, run
NEWGROUP.EXE to add new groups to each, create a signature file,
edited each of the Yarn CONFIG files, etc., etc., as detailed
below in Sections 27.00, 28.00, and 29.00)

I ran YDINSTL.CMD once for the Advantis user, and again for the
WorldNet user.  YDINSTL lets you key in home and yarn directories
for any correctly-set-up Yarn user so you do not need to fool with
CONFIG.SYS again.

NOTE:  For the WorldNet installation, when I had set up the Dial-
Other-Internet-Provider (SLIPPM) to dial in, I assigned the name
WORLDNET (all-uppercase preferred) to the dialup entry.  So, when
YDINSTL.CMD is run specifying E:\WORLDNET as the home and yarn
directories and choosing connection_type 4 and SLIPPM to connect,
YDINSTL presents me with a menu of TCPOS2.INI applications to
choose from, one of which is WORLDNET, in the exact upper-case/
lower-case form (all-uppercase) that I used as my SLIPPM entry
name when I configured SLIPPM for the connection.


8.00   WHAT DOES YDINSTL.CMD DO?
o Fetches information, parameters, etc.

o Wherever  it can, it presents menus for you to choose from when
you need to make selections

o Copies files from a temporary directory to the user HOME
directory

o Creates five customized ReXX programs for each installation,
copying them to the respective home directory

Functionality of four of these:
    - YARNSHELL.CMD   Opens (starts) YARN for that user
                        (to read news and mail, and to
                        create mail, posts and replies)

    - YARNUTIL.CMD    Prompts for and runs YARN utility
                        programs for that user

    - RENEWZIP.CMD    Allows you to restore a reply-packet
                        (.ZIP) if during sending of mail a
                        glitch was encountered

    - LOGOFF.CMD      Helps assure log off by shutting
                        down the IAK Dialer, SLIPPM, PPP,
                        SLIP, SLATTACH, IN-JOY.  Uses
                        IN-JOY's KILLJOY.EXE in order to
                        close down IN-JOY, if KILLJOY was
                        found when LOGOFF was created by
                        YDINSTL.CMD.

Another customized program (OBJECTS.CMD) restores the desktop
folder and its objects if you have intentionally or accidentally
deleted it.

o YDINSTL creates a Desktop Folder unique to each installation,
with objects for the four programs whose functions we have just
described, and a fifth object for running YARNDIAL.CMD.

The folder name contains the name of the user's home directory, so
YARNDIAL desktop folders, each for a different user, will be
distinct from each other.


9.00   .CMD FILES CREATED - MEANING OF CUSTOMIZATION
The ReXX files created by the installer are customized in the
sense that the OS/2 environment variables for HOME and YARN,
paths, and directory structures apply specifically to that
installation.

Unless you change where files are located, LOGOFF.CMD, regardless
of the home directory for which it is customized, will perform
very nearly exactly the same shut-down functionality.  Thus for a
multi-user installation, one "centrally available" LOGOFF.CMD
shadow can be used whatever the user for which it was installed.

Customizing ReXX utilities for each user means that once you've
completed installation of YARNDIAL with YDINSTL.CMD you no longer
need to have a HOME or YARN environment variable in your
CONFIG.SYS file.  Since some other programs want their own HOME
variable set and don't share well, this will prove a great
convenience to some of you and of no interest to others.


10.00   RECREATING OBJECTS (RUNNING OBJECTS.CMD): A PECULIARITY
OBJECTS.CMD as mentioned can recreate objects if you delete them.
Be aware (and this is identified as as a bug at the end of this
document even though in reality it may be a "feature" rather than
a "bug") that if you have moved the YARNDIAL desktop folder you
created during an installation with YDINSTL (for example into
another desktop folder), if you rerun YDINSTL or run OBJECTS.CMD
to recreate the folder on the desktop, the folder does not appear
on the desktop, but instead the one you moved to a new location is
refreshed.  Only if you delete the desktop folder (instead of
moving it) will it be RECREATED ON THE DESKTOP.


11.00   WARP, SOUPER, YARN: VERSIONS TESTED
This version of YARNDIAL and its installer have been tested by me
only on machines running OS/2 Warp Connect with TCPIP and Internet
stuff installed as part of the Warp installation.  Beta testers
have used it on machines running the Merlin beta.  Version 1.32
corrected an incompatibility created by the new format of output
from the NETSTAT utility.  NETSTAT is called by YARNDIAL.

YARNDIAL should run on any OS/2 Warp setup.  If you use the Dial-
Other-Internet-Providers utility (slippm.exe), you will need to
get the upgraded version of TCP/IP and SLIPPM (2.0 or higher).
That should be available by connecting to an updates ftp site.
See Section 33.00 for a link.

If you have installed TCPIP and the OS/2 internet stuff
successfully to OS/2 2.1, I would expect YARNDIAL and its
installer to work.  If anyone tries this under OS/2 2.1 or 2.11, I
would appreciate feedback and if there are problems, I will try
my best to help out.


12.00  YOU HAVE NOT INSTALLED YARN AND SOUPER?
Sections 27.00, 28.00 and 29.00 have very detailed instructions.


13.00  HISTORY
YARNDIAL started out as a ReXX program which in the beginning did
little more than do the work of an flock of OS/2 batch (.CMD)
programs to automate dialup, automate the operations of Souper and
Yarn to get mail and news and send mail and posts, and - to create
a user-friendly menu-driven installer and to creatthen close the
connection.  ReXX offered an easy-to-program user interface for
unattended operation once YARNDIAL was started. ReXX allowed me to
set up menus much more easily than with batch programs.

The earliest versions of YARNDIAL were configured by editing them
with a text editor.  As more and more features and variables were
added through a succession of beta versions, editing became more
extensive and required more knowledge on the part of the user.
Thus, configuration by editing YARNDIAL.CMD was both tedious and
prone to user error.

I decided -- starting with v. 1.3 -- to develop an installer to provide
a friendlier set up.  The installer (YDINSTL.CMD) creates a unique data
file in each Yarn user's home directory to store parameters.
YDINSTL.CMD does its thing with minimal need to study this external
documentation you are now reading.  Most input screens either request
the input of information twice so that verification is accomplished by
duplication, or it checks for existence of files or directories and
accomplishes verification automatically.

   13.10   VERSION HISTORY
      13.11   YARNDIAL.CMD AND ITS COMPANION INSTALLER
               YDINSTL.CMD

24 Sep 96   GA Release 1.40 (YARNDIAL.CMD and YDINSTL.CMD)
   Versions set to 1.40 for both YARNDIAL and YDINSTL.

   Fixed bug that interfered with correct recognition of an existing
   IN-JOY session.  Output from running nslookup.exe is now examined
   to further aid in pinning down details of such a session.

   Minor changes in optional kill-connection-on-exit capability.
   Other small changes and features added.


15 Aug 96 - 17Sep96 versions 1.32x - 1.34(beta) (several)
   For IN-JOY dialer, added ability (optional) to wipe out phantom
   router interfaces left up after IN-JOY shuts down.

   Further improvement in router interface recognition.

   Optional prompting during the install for all parameters
   needed to run Souper, so you do not absolutely need to set up
   slippm.exe to use (for example) in-joy.  Configuration of
   slippm for installation of YARNDIAL for dialers other than the
   IAK dialer and SLIPPM itself and ILINK/2 is still strongly
   recommended as it is a time-saver.

   Added feature that YARNDIAL can be run either to kill the
   connection or not to kill it when YARNDIAL finishes.
   Improved ability to distinguish which connection is up if one
   is up when YARNDIAL starts.

   Eliminated need for tempfile in wait-for-interface routines.

11 Aug 96 v. 1.32(beta)
   Changed the YARNDIAL wait-for-interface and related subroutines
   to accomodate a changed netstat.exe released as part of the
   Merlin beta.

   Changed menuing of dialer support in the installer.  ILINK/2 is
   now supported as a menu item. You can also specify other
   dialers not specifically mentioned in dialer menus.

25 Jul 96 v. 1.31 (beta)
   Improved error-trapping.  Added variable to toggle error-
   trapping on and off in both YARNDIAL.CMD and YDINSTL.CMD using
   the new local_error_trapping variable.

19 Jul 96 v. 1.3 (beta)
   Numerous additions, major cleanup of the code.  Added a
   separate installer (YDINSTL.CMD, v. 09(beta)).

11 Jun 95        YRNDIAL1 (v 1.1) (NO INSTALLER)
   Fixed screwed up backing up of replies .Zip file

11 Jun 95        YARNDIAL (1.0, original)


14.00  SHOULD YOU UPGRADE ANYTHING BEFORE YOU INSTALL?
If you are using the Warp IAK Dialer, or using (or intend to use)
the IBM Dial-Other-Internet-Providers utility (SLIPPM), you may
need to update. That should be available by connecting to an
updates ftp site.  See Section 33.00 for reference to a link.


   14.10   SOUPER
There were some major changes in recent SOUPER versions.  You
should be using SOUPER 14 or 15.  I cannot be sure earlier
versions will be able digest all of the command-line arguments I
have tacked on to Souper when YARNDIAL runs.


   14.20   IBM/ADVANTIS IAK DIALER
            (FOR CONNECTION TO ADVANTIS ONLY)
If your dialer is version lower than 1.33, you should upgrade.  As
of this writing the latest dialer is v. 1.65.  You can upgrade by
signing on to Advantis in the usual way, double clicking on the
Retrieve Software Updates Icon, and downloading the latest Dialer.
Installation is automatic if you go that route.  Upgrades may also
be available off ftp sites supported by IBM/Advantis.

   14.30   SLIPPM.EXE (DIAL-OTHER-INTERNET-PROVIDERS UTILITY
            AND SLIP UPGRADES)
This utility allows you to connect to a provider other than
Advantis by either SLIP or PPP, but you may need to get the most
recent version or update SLIP and TCPIP.

If you installed TCPIP and Internet Access as part of a Warp
Connect installation, you are OK.  (Note: If you installed Warp
Connect, you should have installed the Internet Connection
features only as part of the Warp Connect installation or in a
post-installation using one of the Selective Install icons in the
Warp Connect OS/2 System folder, not from the Bonus Pak).

If you are running Warp 3.0 (not Warp Connect) you will have
installed the Internet Access Kit from the Bonus Pak.  You should
upgrade to SLIPPM v 2.0 and the latest TCPIP, if you have not
already done so.  That should be available by connecting to an
updates ftp site.  See Section 33.00 for reference to a link.


15.00   BEFORE YOU RUN YDINSTL.CMD
Yarn and Souper must be correctly installed.

You must be able to connect with your Internet Service Provider
with the IAK Dialer, SLIPPM, IN-JOY, ILINK/2, a PPP dialup string,
or a SLIP dialup string, or some other dialer.

If you are just using the IAK Dialer,  you do not need to set up
to connect via SLIPPM, the Dial-Other-Internet-Providers
utility.  If otherwise, you should go through the motions of
setting up the SLIPPM to connect to your provider.  And in setting
up SLIPPM, you MUST fill in the names of your news server, your
mail gateway (i.e., your SMTP server), your POP mail server, your
pop login ID, and your pop password even though those are not
mandatory parameters for operation of SLIPPM.

WHY DO THIS?
Unlike SLIPPM, IN-JOY is a connect-only program and does not store
such information as news server, mail gateway, or other similar
information which programs like YARNDIAL needs as parameters.
SLIPPM and the IBM/Advantis IAK Dialer do, using their respective
.INI files, TCPOS2.INI and DIALER.INI.  Furthermore, SLIPPM.EXE,
PPP.EXE, SLIP.EXE use the TCPOS2.INI file to record information
about the current connection.  IN-JOY does not write to TCPOS2.INI
but does have some information aboutr the current connection in
the RESOLV file.

This behind-the-scenes use of the DOIP utility applies to use of a
PPP.EXE or SLIP.EXE dialup string, and use of most other dialers
including IN-JOY and excluding only the IAK dialer.  IN-JOY does
not store all of what is important for YARNDIAL's purposes.
Rather IN-JOY just dials and connects.


16.00   NOTES ON USING THE IN-JOY DIALER
When you set up IN-JOY, it is strongly recommended that you assign
a unique interface name for each IN-JOY host connection you set
up, and different from interface names that may be in use by other
dialers or network connections.

"Interface Name" in IN-JOY is an option on the PPP page (and
presumably will be an option on the SLIP page when SLIP is
supported.  You can use up to 5 letters (all letters; no numbers)
and I suggest (it is not mandatory) you use all 5 positions.  This
gives you 11,881,376 different combinations ignoring upper/lower
case distinctions and makes it overwhelmingly likely that the name
you assign will not accidentally coincide with more common,
shorter names (most common - ignoring case: PPP, SL, SLIP, LAN,
L).  Case, though valid in some interface-name discriminations, is
not important to YARNDIAL's interface-checking routines.

How to identify the current connection if the TCPOS2.INI file is
not written-to by IN-JOY?  One very easy way is if we have a
UNIQUE name for the interface.  NETSTAT.EXE -r returns active
interface routing information, and YARNDIAL can analyze that
information.  Thus, by checking first whether IN-JOY is the dialer
in use, and then comparing the router interface name against the
one in the IN-JOY host configuration data file that we stored in
YD_PARMS.DAT, we can positively ID whether an IN-JOY connection
corresponds to our YARNDIAL user.

The logic is in the get_current_connection() subroutine in
YARNDIAL.CMD and is somewhat complex.  Future versions will no
doubt see changes focussed on that area.

A PROBLEM WITH IN-JOY
I have only encountered one problem with IN-JOY and that problem
is that sometimes when IN-JOY terminates it does not remove the
interface routing that NETSTAT -r sees when it checks to see if we
are connected to our provider.  Thus if a phantom interface is
left, YARNDIAL dials in, waits for the interface to appear in the
NETSTAT -r output, and it of course sees one immediately.  So it
goes on to get/send mail and news.  But we are not really
connected, so YARNDIAL will sense an error condition and quit.
Not good.

Starting with v. 1.34 of YARNDIAL, you can use (by editing
YD_PARMS.DAT) a new INTERFACE_REMOVAL variable that allows
you to optionally kill such interfaces when they are left "up" at the
conclusion of YARNDIAL.

Default is INTERFACE_REMOVAL=0 and no interfaces are removed.

SETTING INTERFACE_REMOVAL:
 INTERFACE_REMOVAL=0    Use this if you regularly establish
   simultaneous connections via SLIP or PPP through more than one
   COM port at a time.  But if phantom routings are left by
   IN-JOY, you will have to live with the problem.  Choose this if
   you never use IN-JOY.
 INTERFACE_REMOVAL=1    Deletes any routing entries left standing
   but only if IN-JOY is your dialer and if the interf_prefix in
   the routing entry matches IN-JOY's.  Suggestion: set the
   interface name in one of the IN-JOY OPTIONS pages to something
   unique for your connection to achieve maximum selectivity
   during operation of interface_removal = 1 (an IN-JOY interface
   name up to five letters long can be used.  Letters only.)
 INTERFACE_REMOVAL = 2     Regardless of the dialer and whatever is
   stored as the interf_prefix, deletes all routing entries at
   shut_down of YARNDIAL.  If you have a problem with phantom
   routings using IN-JOY and never expect to have to make
   simultaneous connections via SLIP or PPP through more than one
   COM port at a time or on your network, try setting
   interface_removal = 2.

If INTERFACE_REMOVAL is set equal to 1 or 2 and a routing is left up
when YARNDIAL exits, the routing is deleted and a message indicating
deletion of the routing appears, with indication of the destination
and router addresses.  The message appears after a line that starts:

   Killing dialers...

and will look like the following:

  delete net 166.72.0.0:  router 166.72.86.98

The two addresses in decimal dot notation are the respective destination
and router addresses that would be reported out were NETSAT.EXE -r to
be run while the phantom routing was up.


WHY SET UP SLIPPM EVEN IF USING IN-JOY?
It is a good idea to set up SLIPPM to connect to your provider
even if you have no intention of using SLIPPM to dial the
provider.  The SLIPPM setup stores parameters in the TCPOS2.INI
file in a manner which makes them most readily available to
YARNDIAL's installer.  As mentioned earlier, in setting up SLIPPM,
you MUST fill in the names of your news server, your mail gateway
(i.e., your SMTP server), your POP mail server, your pop login ID,
and your pop password.  YARNDIAL needs that information.  It is
not mandatory for SLIPPM operation.


17.00   ABOUT THE FIX-INTERRUPTED-IMPORT OPTION ON THE MAIN
        YARNDIAL MENU
What does that do when we've selected it?  First, it assumes
soup.zip might not have been properly created.  So we try to zip
up a file named areas and the various .msg files into an archive
named soup.zip. Shouldn't do any harm if soup.zip already existed
or if we could not find areas or any .msg files.

Then it tries to import soup.zip into YARN (by running import.exe
soup.zip).  Again, no harm done if there is no soup.zip.

Then REBUILD.EXE -s is run, which tries to fix YARN's spool and
history files.

Finally REBUILD.EXE -o is run.  This action tries to rebuild
YARN's history and overview files.

You may see some zip errors.  Ignore them.  They probably mean
that the .zip file being sought was already processed.  You may
also see strange errors such as

          Assertion failed inscur <size   etc. etc >

then after the Fix-Inerrupted-Import option has gone its course,
re-run it.  It should run OK and should (hope springs eternal)
still correct things.

I've only seen that error (once) when I was importing news.  I ran
my Fix option, saw the error first time through, then ran the Fix
option again and did not see the error again.  The rebuild went
OK.


18.00   SOUPER COMMAND-LINE OPTIONS
YARNDIAL calls up Souper with command-line options to control
whether mail or news is retrieved, or mail, posts, replies are
sent.  These command-line options can be changed or added-to by
editing the YD_PARMS.DAT file created in your home directory after
installation is completed.

These three elements in YD_PARMS.DAT

        getmail_xtra_options=
        getnews_xtra_options=
        send_xtra_options=

are what gets edited.  Read the Souper documentation before you
make changes.  SOUPER(.EXE) is omitted from these statements.
Thus, if you wanted to have Souper run as

        SOUPER.EXE -r

to retrieve news  without updating the NEWSRC file, you would
change getnews_xtra_options to read

        getnews_xtra_options=-r

The Souper-get-news and Souper-get-mail options are divided up
into _std_ and _xtra_.  DO NOT ALTER OR EDIT the _std_ options.
They are set up to separate getting mail and getting news so that
you can choose one, the other, or both.

The _std_  options all have Souper running with its -i option.
Souper -i  ensures that the configuration settings for Souper such
as mail server, mail gateway, news server, etc., all come from
YD_PARMS.DAT.

YDINSTL allows you to choose the  -k option (set maximum size of
news-packet), the -l option (that's a lower case "L") (kills
articles that contain more than some number you set of lines in
the body), and the -a option (new newsgroups added).  YARNDIAL
allows you to revise settings on a one-time-only basis for -k and
-l options.  It also lets you choose the -r option on a one-time-
only basis but only lets you change it for mail.  If you select
read-only, you do not empty your POP3 mailbox of mail that you
retrieve.  I use this when I am retrieving mail at a machine other
than my "home" machine.

FROM YARNDIAL you can also call up the -c option on a one-time-
only basis (catch up on news: mark as read all but last n articles
in each newsgroup).

Any of the Souper command-line options except -c can be set by
editing YD_PARMS.DAT.  If you edit, edit (add, remove, change)
the _xtra_options entries.  Don't mess with the _std_options ones.

The -c option cannot usually be added as an option by simply
editing YD_PARMS.DAT because Souper expects -c to be used like so:

        Souper -c 100

or together with the -i option:

        Souper -i -c 100

YARNDIAL, when you select to do catchup, runs the latter example
of use of the -c option.

When you are connected to your news server and Souper -c xxx is
run, article numbers marked as read are appropriately incremented
in your NEWSRC file.  Then, while still logged on to your news
server, YARNDIAL then passes you to a new menu where you can hoose
to actually download the remaining unread ones, or get mail, or
send, etc.


19.00   ISSUES THAT MAY COME UP DURING OR AFTER INSTALL
A unique YD_PARMS.DAT parameter file is created for each
installation.  It is stored in the home directory which is also
unique for each user.  ALL user-definable parameters needed by
YARNDIAL are in that file so that in theory the file may be
manually created, without going through YDINSTL.


20.00   MANUAL INSTALL
If you are about to try a manual installation (not recommended),
an install option is provided that will prompt you for key
parameters.  It usually will provide a functional installation at
that point, but if it does not, you will need to edit YD_PARMS.DAT
to complete the installation.  Godd luck!  It is much easier to
configure SLIPPM!

"I'VE GOT MY PPP.EXE or SLIP.EXE DIALUP STRING AND IT WORKS"
Set up the SLIPPM Dial-Other-Internet-Providers utility anyway
because YDINSTL needs its parameter library.

Run YDINSTL.CMD  selecting connection_type as 3, and after the
installation is done, edit dialup_string in the YD_PARMS.DAT file,
setting

  dialup_string='start' /N abracadabra
        (where abracadabra your complete dial up string which will
        start with PPP.EXE or SLIP.EXE and extend on forever)

The 'start' is important (it is START.EXE).


21.00   MANUAL INSTALL: THE PASSWORD PROBLEM
We encode passwords in YDINSTL.CMD so they will not be exposed in
their original form in YD_PARMS.DAT to the casual eye.  When
YARNDIAL runs, it dencodes them.  If you are trying to manually
configure YD_PARMS.DAT, you may need to create encrypted passwords
for the adv_password, PWD and POP_PWD fields.

This can be done with YDINSTL.CMD using its ENCRYPT command-line
option.  If you run YDINSTL.CMD from an OS/2 command line as
follows:

        YDINSTL.CMD encrypt MyPassword

you will see a line on the screen

        encrypted=xxxxxxxxxxx

where xxxxxxxxxxx will be the encryption of MyPassword.  Other
help info will be displayed.  The number of characters in the
encrypted string will be indicated.

Reference will also be made to a file named word.$$$, which is
created in the same directory from which YDINSTL.CMD with the
encrypt option was run.  The file will contain the same line of
text that was echoed to the screen, and will also indicate the
length of the encrypted password to aid in accurately cutting-and-
pasting it into YD_PARMS.DAT.

Hint: Change to the directory in which YDINSTL.CMD resides before
running YDINSTL.CMD encrypt MyPassword


22.00  CONNECTION_TYPE: THE DIFFERENT CHOICES
CONNECTION_TYPE can be 1 or 3-7.  Very rarely are you likely to
use other than 1, 3 or 4.  Selecting 4 during install brings up a
sub-menu of dialer options.


   1 Installed for Advantis via IAK Dialer.
   2 (Reserved)
   3 Installed for use of a slip.exe or ppp.exe dialup string.
   4 Installed for SLIPPM (IBM's Dial-Other-Internet-Providers.
     Utility) or a SLIPPM replacement such as ILINK/2, IN-JOY,
     etc.
   5 You chose manual configuration: to be prompted for key
     parameters
     followed by manually editing this file as necessary.
   6 Pot-Luck:  Tries to use any connection that happens to be
     established.  Connection must be made BEFORE you start
     YarnDial.
   7 Like 6, but does not check for a connection, and uses the
     string
     in dialup_string to dial.
Anything but 1 or 3-7 for connection_type is an error
condition.


23.00  MORE ABOUT DIALUP_STRING: A PROGRAMMING NOTE
YARNDIAL executes dialup_string by doing:

                 interpret dialup_string

What you enter for dialup_string should consist of the OS/2
executable, the word start (which is the OS/2 executable
START.EXE), plus the dialer executable such as ppp.exe,
slippm.exe, etc., plus any arguments.  Quotes are used where
appropriate for OS/2 executables.  The positioning of quotes is
beyond the scope of this document, but if you have problems, I'll
be glad to try to help ([e-mail]).

Omit the word interpret but always include start.  Depending on
your dialer, you may or may not want to run 'start /N' or 'start'
without the /N or 'Start /c'.  For IN-JOY, the /c should be used
so the OS/2 window is closed after all is done; for SLIPPM it
should not be used.

Below are actual, working, verbatim dialup_strings for real
installations.  Where host_app or account or user, etc., appear as
arguments, those arguments are evaluated to what values the
variables in question have assigned to them.

A slippm dialup_string (connection_type 4):

        dialup_string='start SLIPPM.EXE' host_app

A dialup_string for use of the IAK Dialer (connection_type 1):

        dialup_string='start DIALER.EXE' account user password

A dialup_string for the IN-JOY Dialer ( connection_type 4).  Note
here we need to change to the IN-JOY directory before executing
IN-JOY.EXE:

       dialup_string=do; 'D:'; 'cd D:\IN-JOY09'; 'start /N D:\IN-
JOY09\IN-JOY.EXE' host_app; end

In all of the above, YARNDIAL's use of the ReXX function interpret
in execution of the string will mean that host_app is evaluated to
whatever is assigned to it in YD_PARMS.DAT.


24.00  ZIP AND UNZIP FILES
You can probably use a lot of different compression/uncompress
utilities.  Having used InfoZip OS/2 zip and unzip executables now
for years, there is in my opinion no reason not to prefer them.
The installation as much as invites you to be using them.  I am
assuming that if you don't use OS/2 InfoZip utilities you are in
their place using PkWare's version 2.04G zip and unzip programs.
If you are using something else, there is some help provided below
but my own experience curve is a blank.

25.00 COMPRESSION EXECUTABLES: OS/2 VERSUS MS-DOS
If the zip and unzip programs are OS/2 executables (e.g., as the
OS/2 ports from InfoZip), YD_PARMS.DAT will show only the program
names (with paths), along with the appropriate options.  The
latest InfoZip utilities for OS/2 can be downloaded as archives
unz520x2.zip and zip21x2.exe or zip21c2.exe.

If the compression utility programs are MS-DOS executables (e.g.,
PkWare's PkZip v 2.04G), you must have the OS/2 command processor
call them. OS/2's default command processor is CMD.EXE and it
should be used with the /c option, so set

         zip_exe=cmd.exe /c zip    plus options

Examples of zip and unzip options
        For OS/2 InfoZip                zip -0m
        For OS/2 InfoZip                unzip -o

        For MS-DOS PkWare        zip -m -u -o
        For MS-DOS PkWare        unzip -o

26.00  SOME OTHER BREED OF COMPRESSION UTILITIES?
If you want to use another pair of compress/uncompress utilitites,
you will need to set them up carefully.  Have the command
processor call the utilities if they are MS-DOS and not OS/2
executables, and set the respective compress and uncompress
options based on the documentation provided for the particular zip
and unzip utilities.

To help decide on options for some unconventional choice of zip
and unzip utilities, you must know what the options do.  Those for
the InfoZip programs are decoded below:

        ZIP -0m   (That's a zero not a letter "O") (This is
           the  -0 option combined with the -m option)
           -0 means we import the files into the zip package
           with no compression.

           The -m option means we move files in, replacing any
           of the same name, and once they are in we erase the
           originals.

        UnZIP -o  (That's a lower case letter "o" not a zero.)
           -o overwrites files without asking


27.00  FILES FOR SETTING UP YARN AND SOUPER FROM SCRATCH
        Section 29.00 is a detailed roadmap for the
installation of YARN and SOUPER.  It assumes you are doing a
single-user installation or installing for the first user in a
multi-user installation.  Section 28.00 covers the installation of
the three optional files.  Refer to Section 33.00 for sources of
these files.

Files needed:
   EMXRT09B.ZIP      (optional if Souper is version 14 or
                        higher, but still recommended)
   METAMAIL.ZIP      (optional but recommended)
   MIME64.ZIP        (optional but recommended) (other mime en-
                        or de-coders are available)
   SOUPER15.ZIP      latest version
   YRN2_091.ZIP     latest version. YRN2_090.ZIP is more readily
                    available.


28.00  INSTALLATION OF EMXRT09B, METAMAIL, MIME64 (RECOMMENDED)

   28.10   EMXRT09B.ZIP (OPTIONAL depending on Souper version)
Souper versions 14 or higher do not require this.  However, this
is needed if you want to use metamail to handle mime-encoded
attachments.  It is also needed if you intend to use programs such
as mime64 to encode into mime for attachment to mail and posts, or
to decode mime messages outside of the Yarn and metamail
environment.  It is recommended you install emxrt regardless of
the version level of Souper you are using.

Installation of EMXRT:
Copy emxrt09b.zip into an empty folder (on an HPFS drive if you
have a choice) and unzip, retaining directory structure.  Use of
the InfoZip utilities (latest unzip is in unzip520x2.zip)
automatically retains the directory structure as a default option.
If you use MS-DOS PkWare unzip utility (pkunz204.zip) you need to
unzip with the command:  unzip -d emxrt09b to retain the directory
structure.

EMXRT09B.ZIP when it unzips creates an emx parent folder (most
.zip archives do not create a parent folder).  There are a lot of
files in emxrt09b.zip and it just makes good sense to unzip it
into a separate directory to contain everything in case of an
unzipping error.  In which case there is only one folder cleanly
isolated to delete.

After unzipping, open the temporary folder and you should see only
one folder named emx.  If not, and you see a horrendous number of
files, that means you did not re-create the directory structure.
You need to!

Assuming you only see the one folder named emx, drag that to
whatever disk you want to install emx to (lets assume D:).  Now
you have a D:\emx subdirectory with all of the emx files in
subdirectories under d:\emx.  You can now delete the emxrt09b.zip.

Edit your CONFIG.SYS file.  Add
        D:\emx\dll to the LIBPATH statement
        D:\emx\bin to the PATH statement

Reboot to complete the installation of emxrt.


   28.20   MIME64.ZIP (OPTIONAL) (Utility to encode/decode mime)
Same procedure as for metamail.  Create a directory d:\mime64 and
unzip mime64.zip into it.  No need for any changes in CONFIG.SYS.

Using MIME64:  see Section 28.323  DECODING MIME WITH MIME64.EXE.


   28.30   METAMAIL.ZIP (OPTIONAL)
Metamail is needed if you want to be able to decode incoming mime
attachments, or attach encoded ones automatically from within
Yarn.

Installation of Metamail:
Create a subdirectory named metamail on the drive where you want
to install it (create, say, d:\metamail).  Place on an HPFS drive
if you have a choice.  Copy metamail.zip into that empty folder,
and unzip it, retaining any subdirectory structure.  I do NOT add
metamail to my path statement in CONFIG.SYS; but rather, I include
the full path to metamail in the Yarn CONFIG file so in Yarn's
CONFIG file I might have

      decode-mime=d:\metamail\metamail %f

That is the most common way.  Alternatively, you could use

      decode-mime=cmd.exe /c d:\metamail\meta.cmd %f

where you call metamail from a .CMD file (here META.CMD).  An
example of such a .CMD file is provided further on.  There are
advantages from calling metamail from a .CMD file which we will
cover later.

Finally, to complete the metamail installation, we will create a
file called MAILCAP.YRN, saving it to the d:\metamail directory.
Mine contains the following lines at present.  Your graphics
viewer could be different.  There are also text editors that do
more (in the context of metamail usage), but the basic OS/2 System
Editor (E.EXE) is adequate.  You get the idea, though, with this
example.  Section 28.32  (Metamail Attachments, Operation,
Decoding) explains a bit about what some of these lines do.

NOTE:  the FORWARD slashes below are correct, even for the paths:
a holdover from the UNIX origins of the metamail.exe port to OS/2

# MAILCAP.YRN
text/plain; e.exe %s
text/*; e.exe %s
image/gif; d:/pmview/pmview.exe %s
image/jpeg; d:/pmview/pmview.exe %s
image/jpg; d:/pmview/pmview.exe %s
image/*; c:/viewer/bin/ib %s


Finally, modify your CONFIG.SYS file, adding

                set mailcaps=d:\metamail\mailcap.yrn

For some (DOS) programs that some people like to call up from
mailcap files, it is useful to also add

                device=c:\os2\mdos\ansi.sys

After you have edited CONFIG.SYS, reboot.

My own preference is to write out e-mail with mime-encoded
messages to disk as files (when you read the message in YARN,
press the s key (lower case "S"), enter the full path and name to
save it as (say d:\thing.txt), and press enter to save.  Then I
decode with MIME64 (see Section 28.323  DECODING MIME WITH
MIME64.EXE).


      28.31  METAMAIL TRICKS
When the content-type of a mime-encoded attachment is not
supported by a local viewer, metamail gives you the option to save
the decoded attachment to a file.  You are asked for a file name
to save to (if you don't provide any -- that is, if you just press
ENTER -- nothing is saved even though you may see a default
filename on the screen).  You must type in a name.

You can specify drive and path, but if you do not specify drive
and path, the default path is your yarn home directory.  This is
not a good thing, since, if the name of the file happens to
coincide with the name of a file already in that destination
directory, you will overwrite the existing file.

To re-define the default directory for this operation, you can
call metamail with a command file that changes to a new default
directory first.

To make this change:
alter the decode-mime line in your yarn config file to

decode-mime=cmd.exe /c d:\metamail\meta.cmd %f

This will call metamail.exe from a .CMD file, META.CMD, an example
of which could be:

/* META.CMD */
/* alters default directory
and then runs metamail*/
parse arg fn
'@echo off'
'd:'
'cd d:\inetdata'
'metamail.exe' fn

d:\metamail is the directory where metamail resides and is where
META.CMD will be saved to.

d:\inetdata is a directory where you will save all decoded files.
it is a useful security practice to keep downloaded and decoded
files in one place where you can conveniently do virus-checking,
etc., before they travel far and wide into your file structure.

The new default directory MUST EXIST because metamail will not
create the directory if it does not exist.


     28.32  DOING ATTACHMENTS UNDER YARN, METAMAIL OPERATION,
            DECODING MULTIPART MESSAGES, AND HANDLING NON-
            CONFORMING MIME ATTACHMENTS

In a MIME encoded attachment which has been correctly attached
from within YARN, the attachment will be at the end of the e-mail
or if several in number, in succession at the end with a lot of
boundary and other conditions met.  If conditions are not all met,
the message(s) will not be decoded directly by metamail, but
metamail may give you the opportunity to save the message (or
messages if more than one), or it may not.  Not to worry: if
metamail doesn't decode, you can still save the entire e-mail as
text and that text file can be readily decoded without grief by
MIME64.

     28.321  DOING ATTACHMENTS UNDER YARN, ETC.
To attach:
1.  Post and article, followup, send an e-mail, etc. and get the
ball rolling by pressing r, R, f, F or M from within YARN.
2.  After composing any e-mail text ("Hello, how are you? A file
is attached."), go to the very end of the e-mail and press enter.
The mime attachment will go where your cursor is and this ENTER
assures you of placing the MIME attachment AFTER a carriage
return-linefeed (for that reason I always put an extra carriage
return at the end of my yarn sig file so that my e-mails always
end on a CRLF and not on the last letter of my sig).
3.  Save, exit the editor.
4.  Yarn will present several choices (depending on Yarn version):
   CANCEL
   CHECK SPELLING
   EDIT
   ATTACH FILE
   SEND
5.  Select ATTACH FILE.  You will be prompted for the file name
and a description.  Then press enter and a mime-encoded attachment
will be placed where your cursor was.
6.  Not done Yet.  Save and exit the editor again and select EDIT
from among the choices presented by Yarn.
7. Go down to where the boundary for that attachment is.  Here is
a real-life example of what you will see.

   --1Pz6vtT0gbQ2XEw
   Content-Type: application/octet-stream; name="yrndl132.zip"
   Content-Transfer-Encoding: base64
   Content-ID: <[e-mail]>
   Content-Description: yarndial + ydinstl .cmd files +read.me

   UEsDBBQAAAAIAIc1CyHqvnr/3ms  (etc., start of encoded
attachment)


For a zip file, any other binary, or even a text file, metamail
will decode this and allow you to save it as a binary with a
default name suggested by metamail of yrndl132,zip.

But suppose this file was a graphic name MyDog.gif.  You could
leave it as is and let your recipient save it as a file.

Or you could edit the content-type line, e.g., changing from

   Content-Type: application/octet-stream; name="mydog.gif"

to

   Content-Type: image/gif; name="mydog.gif"

or just

   Content-Type: image/gif;

(refer Section 28.324)

If your recipient has the same MAILCAP file shown above as our
MAILCAP.YRN, when metamail asks: "process this mime attachment?"
and you respond "Y", it will decode the attachment, start up your
viewer (PMVIEW in our mailcap.yrn example), open the decoded .GIF
file and display it.  If you want to save it as a file, you do
that from PMVIEW (using save-as).

Note from this YOU NEVER WANT TO PUT a line like
   application/zip; unzip.exe %s
in your mailcap file, because it would unzip the .ZIP archive and
if there was a directory structure, it could replace existing
files with no opportunity for you to exercise control.

8a.  Still Not done Yet.  Save and exit the editor again.  You can
do another attachment (select ATTACH again, repeat steps 2-7).

   or

8b.  If you have no more attachments, just select SEND and you are
done.

In this example, after the first attachment, we really have a
multipart MIME message.  The first is the original text
("Hello...", and its content line will read something like

   Content-Type: text/plain; charset=ISO-8859-1

this will be opened by our E.EXE editor which our mailcap.yrn file
activates for text/plain content-types.

Then when you've read the message, and you exit the editor, the
second part (the image in our example) is opened by PMVIEW.EXE.


     28.322  DECODING NON-CONFORMING MIME ATTACHMENTS
If you were attaching a message and your cursor was not at the end
of your e-mail text (say it was above your signature), you would
be INSERTING and not ATTACHING (one way to think of it), so the
attachment would go at the cursor position instead of at the end
of the e-mail.  Metamail may not (will not?) recognize this e-mail
as having a valid attachment and will (may) present you with a
message to the effect: "can't recognize this, do you want to save
as text or ignore?".  This will also happen if the initial
boundary (something that starts with two hyphens and
looks like this

          --gc0p4Jq)M2Yt08jU534c0p

but is not preceded by a carriage return (.ie., is in the middle
of a text line like on this line--gc0p4Jq)M2Yt08jU534c0p.

Metamail may let you save the e-mail as text (say as THING.TXT).
Alternatively, From Yarn, after Metamail asks you ("Decode Mime?")
you could respond "N", then save the e-mail as text yourself.  To
do that, press s (lower case "S") while you are reading the e-mail
and after you have responded "N" to "Decode Mime?";  in the window
that appears enter the filename to save to with full path, and
press Enter to complete the save.

Now decode that with MIME64 (next Section).

     28.323  DECODING MIME WITH MIME64.EXE
Say we have saved d:\thing.txt as an e-mail with a single mime-
encoded attachment.  Even if the attachment did not exactly
conform to what metamail expects, running

        mime64 d:\thing.txt

will extract and simultaneously decode, producing a file
$$$$$$$$.$$$ which you can now rename to .zip or .JPG or .TXT or
whatever type it was supposed to be.

Or you could run

        mime64 d:\thing.txt yrndl132.zip

and have it create the correct filename.

Always: I virus check at that point before I do anything more with
it.

I've never mastered how to use the MIME64 program when the text
file being decoded contains more than one MIME-encoded
attachments, but if you use a text editor to separate the text
file you had saved into separate mime parts (each will start and
end with a boundary consting of a double hyphen (--) and some
gibberish, e.g.:

    --gc0p4Jq)M2Yt08jU534c0p

MIME64 will work flawlessly on each section.

So edit so as to preserve the initial and final boundaries for
each mime part, and once they are separated (precision is not
required as long as each separate part has at least the complete
initial- boundary-to-final-boundary encoding), simply run MIME64
on each.


     28.324   CONTENT-TYPE EDITING: MIME ASSOCIATIONS

Content-Type lines that appear in e-mail messages as part of the
MIME attachment (i.e., between the    --gibberish    boundaries)
may look like:

   Content-Type: application/octet-stream; name="yrndl132.zip"
   Content-Type: image/gif; name="mydog.gif"
   Content-Type: image/gif;

The Content-Type application/octet-stream represents the mime-
type/sub-type for binary files in general, i.e., for those with
extensions: .exe, .zip and so forth.  Any file -- binary or
otherwise -- may be typed and transmitted this way.

The Content-Type image/gif represents a mime-type/subtype for a
gif type image file and if the content type in the MIME attachment
header is
       Content-Type: image/gif; name="mydog.gif"

and the line
      image/gif; d:/pmview/pmview.exe %s

appears in your mailcap file (as it does in our MAILCAP.YRN
example, above, replete with its Unix-based forward slashes), when
metamail processes the coded attachment it executes the command

     d:\pmview\pmview.exe mydog.gif

The filename mydog.gif has replace %s and the program called
(pmview.exe) opens the .GIF file mydog.gif.

A list of all recognized MIME media associations is available and
a reference to such a list can be found in Section 33.00.

The general system for how these patterns and associations work in
terms of the practical construction of working mailcap-file lines
can be sketched out as follows:

        (1) For whatever kind of file are you transmitting, define
the content-type/subtype association:  Examples for some image
files: image/gif, image/jpg, image/bmp, image/tif, etc.

gif, jpg, bmp and tif are the subtypes; and correspond to the
.GIF, JPG, .BMP, .TIF standard file extensions (usually the same).

        (2)  Select the program you want to use to open or process
or in general act-on those kinds of files.  Construct one or more
mailcap lines in the form shown below (remember forward slashes
for the paths!)

      image/gif; d:/foodir/foobar.exe %s
      image/jpg; d:/foodir/foobar.exe %s
      image/bmp; d:/foodir/foobar.exe %s
      image/tif; d:/foodir/foobar.exe %s
      image/*; d:/somedir/somebar.exe %s

The last in this train says: any other file of Content-Type image,
if its subtype is not specifcally defined by the other four, try
to open with somebar.exe.


        (3)  Note that if the executable foobar.exe is an MS-DOS
program, it should be called by the OS/2 command processor and
what will appear in the MAILCAP file is

                cmd.exe /c d:/foodir/foobar.exe %s

instead of      d:/foodir/foobar.exe %s



29.00  STEP-BY-STEP-INSTALLATION OF YARN AND SOUPER
1.        Create separate temporary directories for each of
          YRN2_091.ZIP and SOUPER15.ZIP.  For example: create
          d:\yarntemp for yarn and d:\souptemp for Souper.

2.        Copy the yarn zipfile into d:\yarntemp and unzip.

3.        Copy the Souper zipfile into d:\soupzip and unzip.

4.        Decide on a name for a permanent yarn directory and a
          permanent home directory (let's assume you use d:\yarnxx
          and d:\homexx (don't bother to create these directories
          as they will be created for you).

HANDY HINT:  It is possible (my opinion, desirable) to use
the same directory as both the yarn directory and the home
directory.

5.        Edit your CONFIG.SYS file by adding
                SET HOME=d:\homexx
                SET YARN=d:\yarnxx
                SET TZ = EST5EDT

If you insist on using a version of SOUPER earlier than 14 also
add

   SET NNTPSERVER=news-01.ny.us.ibm.net        (or whatever your
                                                news server is)

6.        If you have another program that uses a SET HOME
assignment, REM it out and temporarily add SET HOME=D:\HOMEXX to
your CONFIG.SYS file (then reboot).

You will be able to eliminate the SET HOME and SET YARN
assignments after the installation of YARNDIAL is complete (after
you've run YDINSTL.CMD).

7.        Do not overlook the TZ statement.  You can get errors if
you are way out on local time, and appear to be receiving mail
before it was sent.

8.        If you are not in the eastern time zone set TZ according
to what time zone you are in.  References at the end (Section
) can guide you n how to set up TZ if you live outside the US
or in some exotic location where the time zone is set up in a
weird way.

9.        REBOOT so your new CONFIG.SYS assignments take effect.

10.        Open an OS/2 window or full screen session, and change
directory to the d:\yarntemp directory.

11.        At the [d:\yarntemp] prompt type in ENGLISH D:\YARNXX
(ou s'il tu plais, FRANCAIS D:\YARNXX ).  This creates the
d:\yarnxx directory and copies files from the temporary directory
over to it.

12.        Copy Souper.exe from d:\souptemp to d:\yarnxx.  That's
as good a place as any to keep it.

13.        Add your first user.  In an OS/2 Window or Full Screen
session, change directory to d:\yarnxx.  At the [d:\yarnxx] prompt
type in ADDUSER.EXE and press enter.

ADDUSER.EXE will bring up a screen requiring input of 6
parameters.

For our example (remembering that I am [e-mail]), fill in the
blanks:

home directory                d:\homexx   (must be what you
                                        put in  CONFIG.SYS
                                        as SET HOME)
user ID                       jlevy
host system                   ibm.net
User's full name              Jerry Levy
editor program                cmd /c e.exe
reply-packet file             d:\yarnxx\outgoing\ioxr.zip

Actually, I use the Enhanced Editor, version 6.03 which I
have in the d:\epm6 directory.  So I enter cmd /c d:\epm6\epm.exe
for my editor program.

Make sure these six items are exactly the same as what you
have in Yarn's CONFIG when you edit it (step 19).  Note that the
editor is always called by the command processor cmd.exe with the
/c switch.  This allows re-entry to the editor in the event of
successive calls.

Don't add any other users yet.  We'll get to that later.

14.        CREATE A NEWSRC FILE IN THE HOME DIRECTORY
Use the OS/2 System Editor to create an ASCII file listing all the
newsgroups you want to subscribe to.  After each name pace a colon
(no space between name and colon).  These are the groups that
SOUPER will retrieve news from.  You must also tell Yarn you want
to add them (distinction between getting the news and setting Yarn
up to display).  You must run NEWGROUP.EXE (see step 17) to get
Yarn to understand that these are newsgroups you want Yarn to play
with.

Example of a NEWSRC file with two newsgroups:

comp.os.os2.announce:
comp.os.os2.networking.tcp-ip:

        Save this file as NEWSRC in the home directory
(d:\homexx).  This NEWSRC file is owned by Souper and it records
the article numbers you have downloaded from the news server
("read from the news server" even if you never read the article in
Yarn).

        Another file named NEWSRC will be created automatically to
record which articles you have read from within Yarn (really read,
not just downloaded).  This second NEWSRC file resides in the
home\yarn\ subdirectory (in d:\homexx\yarn in our present
example).

        If you add newsgroups, you add them to the NEWSRC in the
home directory.  You do not add them to the NEWSRC file in the
home\yarn\subdirectory.  Leave that file totally alone.

Remember that whenever you add a new newsgroup, you must also run
NEWGROUP.EXE (step 17).

15.        CREATE A SIGNATURE FILE IN THE HOME DIRECTORY
        Use the OS/2 System Editor to create an ASCII file with
how you want to sign e-mail.  For example, it could consist simply
of something like.

                Jerry Levy ([e-mail])
                Marblehead, MA USA

Hit enter twice after the last character is typed so the file ends
in two carriage return/linefeed pairs.

        Save it to d:\homexx.  Whatever you name it and wherever
you put it (I recommend putting it in d:\homexx), its name and
path should be exactly what you set "signature" equal to in Yarn's
CONFIG file (see step 19).

16.        CREATE A LIST OF ALL NEWS GROUPS (this is a different
file from NEWSRC)

(SEE ALSO: NOTE ABOUT ADDING NEWSGROUPS AFTER STEP 22)
        Create a list of newsgroups you are interested in. It's
like the NEWSRC you created but leave out the colons.  Save it to
d:\homexx.  Name it what you wish (say, NEWSLIST.TXT).  We use it
for doing mass operations on keep days and max-keep days.

        Example:

                alt.org.team-os2
                comp.os.os2.announce

17.        SET KEEP AND MAX-KEEP DAYS FOR NEWS
(SEE ALSO: NOTE ABOUT ADDING NEWSGROUPS AFTER STEP 22)
        METHOD 1:        All groups set at the same time and all
                         set the same way
Change to the d:\yarnxx directory.  Then type in (assuming file
you created above is called newslist.txt):

        NEWGROUP.EXE @e:\homexx\newslist.txt 30 30

and press Enter.

        Don't forget the @ sign and the full path to newslist.txt!
This example sets keep days to 30 (first number) and the max we
keep to 30 (second number).  These numbers should agree with what
to indicated in Yarn's CONFIG file.


        METHOD 2:        Each newsgroup set one at a time, or to
                         add new groups one at a time.

Note that in option1 you used the @ sign so that NEWGROUP.EXE
acted on a file named newslist.txt.

        To set keep and max keep days for one single newsgroup
and/or to add a group to your list, you don't use the @ sign. Have
NEWGROUP.EXE act on the name of the newsgroup.  Type in:

        NEWGROUP.EXE comp.os.os2.announce 30 30

and press enter.

METHOD 1 is greatly to be preferred, because re-running METHOD 2
sometimes keeps adding duplicate menu entries into yarn.

18.        SET UP A MAIL FILTER RULE FOR INCOMING MAIL
This is very important:  Before you try to get mail, you must set
up filter rules and it is useful to have one that places all
incoming e-mail into INBOX.  I only set up this one filter rule.
Some people like to create a regular file system with lots of
rules.

Outline:
        o  At the d:\yarnxx prompt, type in FILTER.EXE and press
enter or
        o  If you've installed YARNDIAL using YDINSTL.CMD, open
the desktop folder you created, double click on the YARNUTIL
utility object, and at the prompt enter FILTER.EXE and press
enter.

You are now at the mail-rule window:
        -Press Insert to enter a new rule, give it a name, tab
         to each field, and press enter when done.
        -Press your keyboard INSERT key to insert a new rule
        -Name this first rule MyMail (example).
        -Select the TO field by tabbing to it or using
         combination of Tab and arrow keys.
        -Enter your e-mail address (e.g., [e-mail])
        -Tab to field to enter save-in folder
        -Enter INBOX as the name (all upper case)
         (it is suggested you use the folder name INBOX for
         your genral incoming mail)
        -Press enter to end the session.

If this went OK, you will see the rule MyMail.  If you don't see
it, you didn't do this correctly so repeat.  Usually this is
because some field (e.g, the save-to folder field) was not filled
in.

19.        Now open the d:\homexx\yarn\CONFIG file in your OS/2
System Editor and inspect all entries.  Edit as necessary with an
ASCII text editor.  Superimposing my own preferences, and
illustrating how some of the entries might look, the changes you
might make are:

       =====START OF YARN CONFIG EDITING=====
These lines (at least) are changed

user=nobody     change to your pop mail user id
                (mine, e.g., is jlevy)

name=No Name    your name (mine is Jerry Levy)

host=nowhere    e.g., mine is ibm.net (stuff after

reply-packet=c:\upload\ioxr.zip
                Here I like to use something such as
                d:\homexx\outgoing\ioxr.zip.  You can use whatever
                you want.  Keep it in the home directory, though
                (d:\homexx in this example)

compress=zip -kjm %f %d/*   I recommend adding full path to the
                               zip file
uncompress=unzip -o %f      Same here

#Reply-To=[e-mail]     Remove the # and change to yours(mine
                            is [e-mail])

#signature=c:\jim\sig       Remove the # and change to
                            d:\homexx\sig.txt, where sig.txt
                            contains how you want to sign your e-
                            mail (e.g.,  name, city, university,
                            etc.)

#address-comments=on        Remove #
#sent-mail=mailed           Definitely remove #
#sent-news=posted           Definitely remove #

Remove the # from each of these 10 items (there is also 1
line you leave the # in for.  It is continuation of a text
line)

# %a            article number
# %C            current newsgroup name
# %f            From: header
# %i            Message-ID: header
# %n            Newsgroups: header
# %t            reply mail address derived from Reply-To: or
                     From: header
# %[name]       value of the header named between the square
                     brackets
# %%            % character
# %?            space character if the WORLDNETribution is
                     less than 80 characters
# \n            new-line character


#mail-attribution=%f wrote:     Remove the #

#followup-attribution=In article %i,%?%f wrote:    Remove the #

#reply-attribution=In article %i, you wrote:       Remove the #

#save-directory = e:\inetdata\newsmail    Remove the # and enter
path
                                          to a default directory
into
                                          which save-to-file mail
goes.
                                          The directory (newsmail
here)
                                          must exist, so create
it.

keep=7            I changed this to 30 (days)

#max-keep=30       I removed the #

#next-screen-context-lines=0       Remove the #.  2 or 3 works
                                   nicely here.
#charset=iso-8859-1               Remove the #

#join-truncated-subjects = 21     Remove the #

#confirm-quit = on                I removed the #

#decode-mime=metamail %f     If you intend to use mime,
                             remove the # and then insert
                             the full path e.g.,
                             decode-mime=d:\metamail\metamail %f)

This final bit of editing of the file concerns colors.  I don't
like the way the default colors show up in a window, so I changed
to this.  Purely my personal preference.

# USENET headers
color header lightgray blue

# specific USENET headers
color header-From yellow blue
color header-Subject yellow blue

# article body
color body white blue

# quoted text
color quote lightgray blue

# more line
color more white cyan

# display colors
color window-border       cyan black
color window-title        cyan black
color window-text         lightgray black

color list-border         cyan blue
color list-title          yellow blue
color list-text           white blue
color list-select         white green

color form-border         yellow blue
color form-title          white blue
color form-text           lightgray blue
color form-active         white cyan
color form-inactive       lightcyan blue

color menu-border         cyan blue
color menu-text           white black
color menu-select         cyan black
color menu-hotkey         lightgray black
color menu-select-hotkey  lightgray white

If you want to try these color settings, just copy and paste this
whole colors Section in place of the defaults in the Yarn CONFIG
file. Save a backup of your original Yarn CONFIG first.

       =====END OF YARN CONFIG EDITING=====



20.   THIS COMPLETES SETTING UP YARN AND SOUPER (SINGLE USER)
At this point you can REM out or remove the SET HOME and SET YARN
environmental settings in CONFIG.SYS.  If you don't need to, of
course, don't bother, but if you had installed another program
which needed its own SET HOME assignment, and you temporarily
REMMED that out, you can now restore it.  Do not remove the SET
TZ=   statement from CONFIG.SYS.

21.   At this point you no longer need your temporary yarn
or Souper directories unless you plan on setting up for multiple
users or multiple providers.  You might consider printing out
documentation files before you wipe these temporaries out.

22.   INSTALLING YARNDIAL WITH YDINSTL.CMD AND TESTING YARN
      AND SOUPER

(SEE ALSO: NOTE ABOUT ADDING NEWSGROUPS AFTER THIS STEP)

SET UP DIALERS
If you are using either SLIPPM (the IBM Dial-Other-Internet-
Providers utility) or the ILINK/2 dialer, you MUST set up
SLIPPM and verify it can connect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.

If you are using either the IN-JOY dialer, or a SLIP.EXE or
PPP.EXE dialup string to connect, you SHOULD set up
SLIPPM and verify it can conect to your provider successfully
before you run YDINSTL.CMD to install YARNDIAL.  This is
because the YARNDIAL installer (YDINSTL.CMD) can extract
parameters from the TCPOS2.INI file used to store SLIPPM
setup information.

In setting up SLIPPM, you MUST fill in the names of your news
server, your mail gateway (i.e., your SMTP server), your POP
mail server, your pop login ID, and your pop password (page 3 of
the SLIPPM settings page).

If you are using the IBM/Advantis IAK Dialer and it is
configured correctly, you are ready to run YDINSTL.CMD to
install YARNDIAL.

After that installation is completed (refer Section 1.00) you can
test YARN and SOUPER with a correctly, fully installed YARNDIAL.

A PRIMER ON USING YARN -- TESTING YOUR INSTALLATION
Start it by opening the desktop folder (YARNDIAL) created after
you ran YDINSTL.  Double-click on the YARN-program object.  When
the window opens, click in the upper-right corner to maximize the
window.

        Press F1.  Brings up the help menu (all functions).

        Press Escape.  Returns you (to Yarn).

        SEND AN E-MAIL TO YOURSELF:  Press Shift M.  Fill in the
blank(s) in the window that comes up.  Press Enter and your editor
should start.  Type in your message.  Do SAVE, close the editor.
The Yarn window will return.  Select SEND (should already be
selected, so press Enter).  Press Escape to exit Yarn.  Now start
YARNDIAL, and when the menu comes up, select the Export option.

        GET THE E-MAIL YOU JUST SENT:  (allow time for your
Internet Service Provider to process it, at most a few seconds if
you provider is worth anything, a minute at most).  Start
YARNDIAL, and select the Get-Mail option to retieve it.

        LOOK AT YOUR FOLDERS:  Now start Yarn again, maximize the
window, do Shift-F.  You should see a Mailed folder and an INBOX
folder (if you retrieved your e-mail). If you'd posted something
to a news group, there would also be a Posted folder.  Select one
of these, press Enter, and you can read your INBOX (in-mail), what
you've Posted or wht you've Mailed.
qqq
        PRINT IT:  While the mail is opened (reading your
message), press s (lower case "S").  In the window that appears
enter prn and press Enter.  You can alternatively enter a file
name (path, too) and save it as a file.  There's an entry in your
Yarn CONFIG file for a default directory where to save news, and
if you omit the path when you enter the save-to filename, it
it goes there.

        To back out successively from where ever you might be in
Yarn: use the Escape key.

        To see command-help: Press F1.  Great function summary!

END OF PRIMER.

30.00  NOTE ABOUT ADDING NEWSGROUPS
Sometimes, and I haven't tried to figure out exactly what has to
happen for YARN to behave this way, even after you add groups to
the home directory NEWSRC, and run NEWGROUP.EXE to add a group and
set keep days, or add a host of groups and set keep days all at
one time by running NEWGROUP.EXE @newslist.txt 30 30 (example),
all groups do not show up in YARN's newsgroup lists when YARN
opens.  Not to worry.  If you press either the minus key or your
Insert key, the groups will show up in a list and you can select
them one by one to add them.  These keys are among the commands
listed when you press F1 to bring up YARN's command-help file.

31.00  SETTING UP AND INSTALLING FOR MULTIPLE USERS
If you do use Yarn and Souper for e-mail, and even if you don't,
you really should set up yourself as a user with ADDUSER.EXE even
if you intend to be the only user.  Most installations are for a
single user and involve only one provider.  (Some guides to
setting up Yarn and Souper advise against doing so, but do it!).

After you have set up for a single user, the best way to add other
users is as follows
        a.   You should already have run YDINSTL.CMD and have set
up YARNDIAL for your first user.
        b.  If you haven't wiped out your temporary yarn and
Souper directories, go back and do steps 10, 11 and 12 again,
setting up a completely new yarn directory.  (If you wiped these
temporary folders out, you'll need to repeat steps 1-12).
        c.  Open up the YARNDIAL SUITE folder which YDINSTL
created on your desktop for your first user, double-click on the
YarnUtil icon and enter ADDUSER.EXE as the utility you want to
run.  Set up a new home directory for this new user by filling in
the parameters called for, just as you did for the first user.
        d.  Run YDINSTL.CMD again (the one you ran for the first
user or the on first user or the one copied over into d:\homexx,
doesn't matter which).  When prompted for your Home and Yarn
directories, key in the ones for this new user.
        d.  Repeat steps 14-16.
        e.  Double-click on YarnUtil in the desktop folder you
just created for the second user, and run  NEWGROUP.EXE (see step
17) and FILTER (see step 18).
        f.  Edit the CONFIG file in the YARN subdirectory of the
new users HOME directory (see step 19).
        g.  You're done setting up for a second user or provider.


32.00   CONNECTION KILLED OR NOT WHEN YARNDIAL ENDS
YARNDIAL was originally designed to shut down the dialer and
disconnect from the phone line when it finishes.  This was part of
the original premise of automating off-line retrieval and sending
of news and mail: letting you walk away from the machine without
racking up unnecessarily high phone bills or access times.

Sometimes, however, you may be on-line, and want to get or send
mail, and then return to whatever you were doing on-line without
having to reconnect.  This feature was implemented to allow you to
do that.

The main menu has seven selections.  If you select the "do-not-
kill-connection" option (either at install time or by making
DO_NOT_KILL_CONNECTION=1 in YD_PARMS.DAT, your seven-selection
choice becomes

       1 2 3 4 5 6 7   Executes functions as shown; goes
                       off-line when done
or
       ! @ # $ % ^ &   Same functions; connection remains up


Note: The ! @ # $ % ^ & choices represent shift-1, shift-2,
through shift-7 on a US-English keyboard.  Those alternate "stay-
connected" keys may be changed to suit your own national keyboard
by editing DNK_STRING in YD_PARMS.DAT.


33.00  WHERE TO GET SOFTWARE AND HELPFUL DOCUMENTATION
(this Section is work in progress)

  ftp-os2.nmsu.edu
mentioned below is a mirror site for the hobbes site
   ftp site (hobbes.nmsu.edu)
Directories are the same for whichever of the two you connect to.
They are the old-reliables and I rely on them below.

Equally,
   ftp.leo.org
will likely have these files but the directory structure is
different than hobbes.  It has a mirror site
   ftp.informatik.tu-muenchen-de

The OS/2 Shareware BBS (703-385-4325) will also likely have
these files.  It can be accessed on the Web as well at
   http://www.os2bbs.com.

A good Web site for searching for software by name or keywords is
   http://castor.acs.oakland.edu/cgi-bin/vsl-front
(those are lower-case "L"'s not "one"'s)

EMXRT09B.ZIP
(optional if Souper is version 14 or higher, but still recommended
because you need it for metamail, and for mime64)
   ftp-os2/nmsu.edu/os2/unix/emx09b/emxrt.zip

METAMAIL.ZIP
(optional but recommended)
   ftp-os2/nmsu.edu/os2/unix/metamail.zip

MIME64.ZIP
(optional but recommended.  Other mime en- or de-coders are
available)
   ftp-os2/nmsu.edu/os2/unix/metamail.zip

SOUPER15.ZIP        latest version
  ftp-os2/nmsu.edu/os2/network/tcpip/souper15.zip
  also, links to it on http://www.vex.net/yarn

YRN2_09x.ZIP        latest version is _091, but _090 is fine.
   ftp-os2/nmsu.edu/os2/network/tcpip/yrn2_090.zip
   links to yrn2_091.zip are on http://www.vex.net/yarn

INfoZip Utilities (ZIP and UNZIP)
   ftp-os2/nmsu.edu/os2/archiver/zip21x2.zip
   ftp-os2/nmsu.edu/os2/archiver/unzip520.zip

UPDATES OF TCP/IP AND SLIPPM
In addition to the usual IBM sites, a good bet is John
Summerfield's web page.
  http://www.iinet.au/~summer/os2/
You will find links to service packages. The IC12657 package is
the latest I could find.  It will take only about 10 minutes to
install.

PPP.DOC
Look for it in the c:\tcpip\etc directory or use the Warp SEEK
utility to find it.

PPPINFO.ZIP by Tony Rall
Links to it in
   http://www.io.org/~tm/bells2.html

SLIPPM.FAQ
   http//www.gnatnet/lstone/FAQ.HTML
   (That's an "L" stone not a "one" stone)

PPDIAL29.ZIP
   ftp-os2/nmsu.edu/os2/network/tcpip/ppdial29.zip
   (Not only for the software but for its documentation)

TZ SETTINGS (Config.sys, time zones)
There is an excellent (readable, complete) discussion in the help
file of the time868 program which can be found at
     ftp-os2/nmsu.edu/os2/network/tcpip/time868b.zip

   Start time868, click on help, and then search 'all sections'
   for TZ.

There is also TZ information in the Master Help Index (it's in the
Warp Information folder).  Search for 'time zone' in the Master
Help Index.

COMPLETE LIST OF MEDIA-TYPES (MIME ASSOCIATIONS)
(MIME TYPE or SUBTYPE and APPLICABLE FILENAME EXTENSIONS)

example : application/octet-stream represents mime type/subtype
for binary files in general, i.e., those with extensions: .exe,
.zip and so forth.
   http://www.isi.edu/in-notes/iana/assignments/media-types
   (document: media-types, plus others in that directory)

ACCESSING RFC's and FYI's, General Internet Information
   General:  try these and wade into them
      http://www.isi.edu/
      http://info.internet.isi.edu/
   Specifically: for RFC's, FYI's:
      http://info,internet.isi.edu/1/in-notes/
        and you will see links
      (note:  that /1/ is a "one" not an "L")
      RFC's that may be of interest for people already confused by
      Mail, MIME and eager to know just how complex it gets:
         RFC1049    Content-type Headers
         RFC1341  Multipurpose-Internet-Mail-Extension (MIME)
         RFC822   ARPA Standard for Internet Messages

GENERAL INFORMATION AND LINKS TO YARN AND SOUPER
FILES, DOCUMENTATION, UTILITIES
   http://www.io.org/~tm/bells2.html and links contained therein
   http://www.vexnet.net/yarn and links contained therein
   http://www.nic.com/~cannon/getyarn.html and links contained
        therein
   ftp://hobbes.nmsu.edu/os2/comm/soupinst.zip
         Steve Withers' install notes



34.00  BUGS AND ERROR-TRAPPING
If you have moved the YARNDIAL desktop folder you created during
an INSTALL (for example into another desktop folder), if you rerun
YDINSTL or run OBJECTS.CMD to recreate the folder on the desktop,
the folder does not appear on the desktop, but instead refreshes
the one you moved into the location you moved it to.

We can trap and identify various types of ReXX error conditions:
Error, Syntax, Failure, Novalue, Halt and Notready, by setting

        local_error_trapping = 1

Default is

        local_error_trapping = 0

but if you have problems, briefly setting this equal to one may
help you identify source of an error.   For some kinds of trapped
errors when local_error_trapping is set =1, the line number
returned in SIGL is either the end of the .CMD file or the line
jumped to upon the error.  In most cases, however, SIGL returns
the offending line.

JL     Marblehead, MA